Skip to main content link. Accesskey S
  • Help
  • HCL Logo
  • HCL Notes and Domino Application Development wiki
  • THIS WIKI IS READ-ONLY. Individual names altered for privacy purposes.
  • HCL Forums and Blogs
  • Home
  • Product Documentation
  • Community Articles
  • Learning Center
  • API Documentation
Search
Community Articles > Developing Applications > Using Domino REST Services > Optimizing DAS data API performance
  • Share Show Menu▼
  • Subscribe Show Menu▼

Recent articles by this author

Community articleOptimizing DAS data API performance
Added by ~Arnold Breamanlen | Edited by ~Arnold Breamanlen on October 3, 2017 | Version 7
expanded Abstract
collapsed Abstract
No abstract provided.
ShowTable of Contents
HideTable of Contents
  • 1 Abstract
  • 2 Introduction
  • 3 View Read Performance
  • 4 Document Read Performance
  • 5 Conclusion

Abstract

Domino Access Services (DAS) is a family of REST APIs built into IBM Domino and available from the XPages Extension Libraryexternal link on OpenNTF.  The DAS data API is used to create, read, update and delete data in any Domino server application.  This article describes some techniques for optimizing the performance of the data API.  It assumes you already have some experience with this API.  For more general information on the data API, see this referenceexternal link.

Introduction

The DAS data API is designed to provide access over HTTP/HTTPS to virtually any Domino server application.  When you use the data API to read a view, an individual document, or other data object, the default response often contains more data than you actually need to implement your application.  Since the data API cannot infer what's important to you, it returns the maximum amount of data.  Fortunately, you can often boost performance by requesting less data.  It's simply a matter of adding one or more query parameters to the request URL.

One example of this is the compact parameter.  This is a boolean query parameter you can use in any GET request.  Consider, for example, the database collection request:

GET /api/data


The response is a potentially large array of databases like this:

[

  {

    "@title": "Administration Requests",

    "@filepath": "admin4.nsf",

    "@replicaid": "852573910361A2F4",

    "@template": "StdR4AdminRequests",

    "@href": "/admin4.nsf/api/data/collections"

  },

  {

    "@title": "Java AgentRunner",

    "@filepath": "AgentRunner.nsf",

    "@replicaid": "8525671400725208",

    "@template": "",

    "@href": "/AgentRunner.nsf/api/data/collections"

  },

  ...

]


By default, the response include lots of white space including spaces and new line characters.  This white space increases readability and is helpful when you are learning about the data API, but it's not necessary as you move your application into production.  You can remove the white space from the response by adding the compact parameter to your request:

GET /api/data?compact=true


Depending on your network bandwidth and the number of databases on your server, this can reliably shave several milliseconds off the database collection response time.  Best of all, the compact parameter is available for all data API GET requests.

View Read Performance

You use the view entry collection resource to read entries in a view or folder.  For example, the following is a simple view read request:

GET /XPagesExt.nsf/api/data/collections/name/AllContacts


The response is an array of view entries like this:

[

  {

    "@href": "/XPagesExt.nsf/api/data/collections/name/AllContacts/unid/39A95ECD82D0DEB485257AB5005BFEE0",

    "@link": {

      "rel": "document",

      "href": "/XPagesExt.nsf/api/data/documents/unid/39A95ECD82D0DEB485257AB5005BFEE0"

    },

    "@entryid": "1-39A95ECD82D0DEB485257AB5005BFEE0",

    "@unid": "39A95ECD82D0DEB485257AB5005BFEE0",

    "@noteid": "5D26",

    "@position": "1",

    "@read": true,

    "@siblings": 10000,

    "@form": "Contact",

    "Id": "CN=Aaron Goodman/O=renovations",

    "FirstName": "Aaron",

    "LastName": "Goodman",

    "EMail": "aaron_goodman@renovations.com",

    "City": "Philadelphia",

    "State": "PA",

    "Created": "2012-11-13T16:44:50Z",

    "$10": "Aaron Goodman"

  },

  {

    "@href": "/XPagesExt.nsf/api/data/collections/name/AllContacts/unid/32898140B9DB45F485257AB5005A9394",

    "@link": {

      "rel": "document",

      "href": "/XPagesExt.nsf/api/data/documents/unid/32898140B9DB45F485257AB5005A9394"

    },

    "@entryid": "2-32898140B9DB45F485257AB5005A9394",

    "@unid": "32898140B9DB45F485257AB5005A9394",

    "@noteid": "D7E",

    "@position": "2",

    "@read": true,

    "@siblings": 10000,

    "@form": "Contact",

    "Id": "CN=Aaron Guerrero/O=renovations",

    "FirstName": "Aaron",

    "LastName": "Guerrero",

    "EMail": "aaron_guerrero@renovations.com",

    "City": "Coral Springs",

    "State": "FL",

    "Created": "2012-11-13T16:29:20Z",

    "$10": "Aaron Guerrero"

  },

  ...

]


By default, the response includes the first page of 10 entries.  You can increase the page size (e.g. count=50) and send subsequent requests for more pages (page=1, page=2, etc.).  

Prior to Domino 9.0.1 FP8, there was virtually no limit to the number entries you could ask for in a single request.  If the view had tens of thousands of entries, you could receive ten thousand (count=10000) or more entries in one response.  However, as of Domino 9.0.1 FP8, the maximum pages size is 100 entries by default.  IBM made this change in response to problem reports citing poor performance when the server was handling hundreds of simultaneous requests for ten thousand or more rows of data.  Since the data API was never designed to support that kind of load, IBM decided to enforce a maximum page size.  This encourages paging through large views and improves overall performance.

NOTE:  We realize this change in behavior has the potential to break existing applications.  You can relax the page size limit with a server Notes.ini setting.  For example, use the following setting to increase the maximum page size to one thousand entries:

DataServiceMaxViewEntries=1000


For best performance under high load, it's best to keep the maximum page size as low as possible.

Of course when optimizing performance, the size of each entry may matter as much as the total number of entries in each page.  Referring to the sample response at the beginning of this section, you will notice two distinct kinds of properties for each entry.  There are system columns (@href, @link, @unid) -- the names of which each begin with an @ -- and there are application-specific properties (Id, FirstName, LastName, etc.).  By default, the response includes all available system columns, but you can improve performance by using the systemcolumns parameter.

Consider a request like this:

GET /XPagesExt.nsf/api/data/collections/name/AllContacts?systemcolumns=0


The response is similar to the previous example, but most system columns are excluded:

[

  {

    "@entryid": "1-39A95ECD82D0DEB485257AB5005BFEE0",

    "Id": "CN=Aaron Goodman/O=renovations",

    "FirstName": "Aaron",

    "LastName": "Goodman",

    "EMail": "aaron_goodman@renovations.com",

    "City": "Philadelphia",

    "State": "PA",

    "Created": "2012-11-13T16:44:50Z",

    "$10": "Aaron Goodman"

  },

  {

    "@entryid": "2-32898140B9DB45F485257AB5005A9394",

    "Id": "CN=Aaron Guerrero/O=renovations",

    "FirstName": "Aaron",

    "LastName": "Guerrero",

    "EMail": "aaron_guerrero@renovations.com",

    "City": "Coral Springs",

    "State": "FL",

    "Created": "2012-11-13T16:29:20Z",

    "$10": "Aaron Guerrero"

  },

  ...

]


Depending on the view design, this can reduce the size of the response by more than 50%.  Not only does it take less time to transfer the response across the network, but the server spends less time reading data from the underlying view -- data you may not need any way.

The value of the systemcolumns property is actually a bit mask where each bit represents a specific system column:

  • @noteid -- 0x0001
  • @unid -- 0x0002
  • @position -- 0x0004
  • @read -- 0x0008
  • @siblings -- 0x0010
  • @descendants -- 0x0020
  • @children -- 0x0040
  • @indent -- 0x0080
  • @form -- 0x0100
  • @category -- 0x0200
  • @response -- 0x0400
  • @href -- 0x0800
  • @link -- 0x1000
  • @score -- 0x2000

So to request the @unid property and no other system columns, you might send a request like this:

GET /XPagesExt.nsf/api/data/collections/name/AllContacts?systemcolumns=0x0002


Or to request just the @unid and @link properties, you might send a request like this:

GET /XPagesExt.nsf/api/data/collections/name/AllContacts?systemcolumns=0x1002


In other words, you can request just the set of system columns you need for your particular application.

Document Read Performance

Conclusion

expanded Attachments (0)
collapsed Attachments (0)
expanded Versions (18)
collapsed Versions (18)
Version Comparison     
VersionDateChanged by              Summary of changes
18Oct 3, 2017, 11:20:16 PM~Chris Chufanabergynds  
17Oct 3, 2017, 5:15:13 PM~Arnold Breamanlen  
16Oct 3, 2017, 5:14:03 PM~Arnold Breamanlen  
15Oct 3, 2017, 5:10:47 PM~Arnold Breamanlen  
14Oct 3, 2017, 5:07:46 PM~Arnold Breamanlen  
13Oct 3, 2017, 5:04:51 PM~Arnold Breamanlen  
12Oct 3, 2017, 4:58:34 PM~Arnold Breamanlen  
11Oct 3, 2017, 4:57:03 PM~Arnold Breamanlen  
10Oct 3, 2017, 4:54:15 PM~Arnold Breamanlen  
9Oct 3, 2017, 4:52:47 PM~Arnold Breamanlen  
8Oct 3, 2017, 4:47:34 PM~Arnold Breamanlen  
This version (7)Oct 3, 2017, 3:52:23 PM~Arnold Breamanlen  
6Oct 3, 2017, 3:50:35 PM~Arnold Breamanlen  
5Oct 3, 2017, 3:40:51 PM~Arnold Breamanlen  
4Oct 3, 2017, 3:39:11 PM~Arnold Breamanlen  
3Oct 3, 2017, 3:35:06 PM~Arnold Breamanlen  
2Oct 3, 2017, 3:32:45 PM~Arnold Breamanlen  
1Oct 3, 2017, 3:30:20 PM~Arnold Breamanlen  
Copy and paste this wiki markup to link to this article from another article in this wiki.
Go ElsewhereStay ConnectedAbout
  • HCL Software
  • HCL Digital Solutions community
  • HCL Software support
  • BlogsDigital Solutions blog
  • Community LinkHCL Software forums and blogs
  • About HCL
  • Privacy
  • Accessibility